---
title: Univer Sheets API
---

Univer Sheets provides professional-grade spreadsheet capabilities, with concepts designed to be as consistent as possible with Microsoft Excel.

## Workbook

A workbook contains multiple worksheets and can be thought of as an Excel file.

The `unitId` can be used as a unique identifier for the workbook.

### Create a Workbook

The [`univerAPI.createWorkbook(data, options)`](https://reference.univer.ai/en-US/classes/FUniver#createworkbook) method creates and returns the `FWorkbook` object.

The [`IWorkbookData`](/guides/sheets/model/workbook-data) is an object that contains the configuration information of the workbook.

```typescript
const fWorkbook = univerAPI.createWorkbook({ id: 'Sheet1', name: 'Sheet1' })
console.log(fWorkbook)
```

Add you can make the workbook not as the active workbook by setting options:

```typescript
const fWorkbook = univerAPI.createWorkbook({ id: 'Sheet1', name: 'Sheet1' }, { makeCurrent: false })
console.log(fWorkbook)

// If you want to switch to this workbook after 3 seconds
setTimeout(() => {
  univerAPI.setCurrent(fWorkbook.getId())
}, 3000)
```

### Get Workbook Data [#get-workbook-data]

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const snapshot = fWorkbook.save()
console.log(snapshot)
```

### Unload Workbook

When you no longer need a `Workbook`, you can call the `disposeUnit` method on the API instance to unload it.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const unitId = fWorkbook?.getId()
if (unitId) {
  univerAPI.disposeUnit(unitId)
}
```

<Callout type="warning">
  When the entire page hosting the Univer instance is destroyed or the route is unloaded, make sure to call the `univer.dispose()` method for cleanup, rather than using `univerAPI.disposeUnit`.
  Also, please note that `univer` and `univerAPI` are different instances. For instructions on how to obtain these instances, refer to the [Installation & Basic Usage](/guides/sheets/getting-started/installation).
</Callout>

### Get Workbook ID

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook?.getId()
```

## Worksheet

Worksheets store table data, worksheets belong to the workbook.

A workbook can contain multiple worksheets, and the names of worksheets in the same workbook cannot be duplicated.

The `subUnitId` can be used to uniquely identify a sheet in a workbook.

### Get Worksheets

Get all sheets in a sheet

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const sheets = fWorkbook.getSheets()
```

Get Active Worksheet

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
```

### Get Worksheet Data

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const sheetSnapshot = fWorksheet.getSheet().getSnapshot()
```

### Create a Worksheet [#create-worksheet]

The following example shows how to create a worksheet using the [`FWorkbook.create`](https://reference.univer.ai/en-US/classes/FWorkbook#create) method.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()

// Create a worksheet named 'Sheet2' with 10 rows and 10 columns
const newSheet = fWorkbook.create('Sheet2', 10, 10)
```

### Remove Worksheet

Remove Worksheet by passing the worksheet instance or the worksheet Id

```typescript
// Delete the second worksheet
const fWorkbook = univerAPI.getActiveWorkbook()
const sheet = fWorkbook.getSheets()[1]
fWorkbook.deleteSheet(sheet)

// The code below deletes the specified worksheet by id
// fWorkbook.deleteSheet(sheet.getSheetId());
```

### Activate Worksheet

Activate the worksheet by passing the worksheet instance or the worksheet Id, or use `FWorksheet.activate()` method.

```typescript
// Activate the second worksheet
const fWorkbook = univerAPI.getActiveWorkbook()
const sheet = fWorkbook.getSheets()[1]
fWorkbook.setActiveSheet(sheet)

// Activates the specified worksheet by id
// fWorkbook.setActiveSheet(sheet.getSheetId());

// Activate the worksheet using the FWorksheet.activate() method
// sheet.activate();
```

### Get Worksheet ID

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
fWorksheet?.getSheetId()
```

### Refresh Worksheet

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
fWorksheet.refreshCanvas()
```

### Worksheet Zoom

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Set zoom ratio to 200%
fWorksheet.zoom(2)
const zoomRatio = fWorksheet.getZoom()
```

### Scroll to Cell

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Scroll to cell D10
const fRange = fWorksheet.getRange('D10')
const row = fRange.getRow()
const column = fRange.getColumn()
fWorksheet.scrollToCell(row, column)

// Get scroll state
const scrollState = fWorksheet.getScrollState()
const { offsetX, offsetY, sheetViewStartColumn, sheetViewStartRow } = scrollState
console.log(scrollState) // sheetViewStartRow: 9, sheetViewStartColumn: 3, offsetX: 0, offsetY: 0
```

## Core Features

### Permission

Reference: [Permission](/guides/sheets/features/core/permission)

### Formula

Reference: [Formula](/guides/sheets/features/core/formula)

### Row and Column

Reference: [Row and Column](/guides/sheets/features/core/row-col)

### Range

Reference: [Range](/guides/sheets/features/core/range-selection#range)

### Selection

Reference: [Selection](/guides/sheets/features/core/range-selection#selection)

### Cell

Reference: [Cell](/guides/sheets/features/core/range-selection#cell)

### Freeze

Reference: [Freeze](/guides/sheets/features/core/freeze)

### Integrating Custom Components into Univer

Reference: [Integrating Custom Components into Univer](/en-US/guides/sheets/ui/components)

## Reference

Please refer to the following API documentation for more information:

- [FWorkbook](https://reference.univer.ai/en-US/classes/FWorkbook)
- [FWorksheet](https://reference.univer.ai/en-US/classes/FWorksheet)
